feat(access): the ADR5 grant/consent/visibility layer - #900

Two vocabulary fixes from ADR5. Neither changes an API response shape.

The table named permission_history records a landowner's consent to physical
site access -- sampling, equipment installation -- which is a domain fact, not
authorization. It is now field_access_consent (model FieldAccessConsent). The
permission_type and permission_allowed columns keep their names, since
permission_type is lexicon-backed and both are published on Thing responses
under the unchanged `permissions` key.

db/permission.py's Permission and base.py's PermissionMixin are deleted. They
were dead: never imported in db/__init__.py, no `permission` table in any
migration, no callers.

release_status was one column carrying two axes -- its lexicon lists draft,
public, private, published and archived next to provisional and final -- so a
record could not be public and provisional at once, which San Acacia data is.
ReleaseMixin now carries data_maturity alongside it. That is not a new
vocabulary: the lexicon category (provisional, in review, approved) and the
column already existed on transducer_observation, whose duplicate declaration
is removed. Nullable, NULL meaning not stated.

No data moves. Rows already marked release_status='provisional' are left
alone; reassigning them across the two axes needs a decision per row and is
tracked in ADR5.

Migration e7c1a9f4b2d8 renames the table (with its primary key constraint and
sequence, so the old name stops appearing in errors) and adds data_maturity to
the 34 other ReleaseMixin tables and the 7 continuum version tables. Verified
down and back up against ocotilloapi_test.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The storage and evaluation half of ADR5. No existing endpoint changes
behavior: the layer goes behind one service before it goes behind all of them.

Four tables. permission_grant holds internal authorization -- principal x
capability x scope, one row per data type. publication_consent holds what a
landowner agreed to publish about their well, per destination and data type,
so "levels yes, chemistry no" is a row rather than institutional memory.
destination is the registry those consent rows point at. authorization_audit
is append-only and is written in the same transaction as every change, because
the first question after an exposure is who granted that, and when.

Two tables rather than one because consent and clearance are decided by
different people on different authority and revoked by different events. One
evaluator rather than two because migration baba91fe5e83 already showed what
independent filtering costs.

domain/access.py holds the rules as plain functions over plain values, so they
are testable without a database and cannot be restated differently by a second
caller. Three invariants live there: default deny, no wildcard data type, and
expiry compared at use rather than swept by a job that can be missed. An
unrecognized scope type denies instead of raising, so a row written by a newer
version of the code never reads as permission to an older one.

services/visibility.py is the only place that answers "may this principal" and
"what does this destination get". api/access.py is its one tenant: grant and
consent administration, the destination registry, and a /access/decision
introspection route. The prefix is /access because /publication is already the
bibliography. Writes are Admin, reads are Viewer.

The five vocabularies are lexicon categories seeded from core/lexicon.json,
not enums in code, so adding a destination kind is not a deploy. Data types
are deliberately coarse -- water level, water chemistry, well construction,
site metadata -- and there is deliberately no term meaning "all".

Not included: no pre-existing endpoint consults the layer, so the OGC views
still publish on release_status; field projection is the next step; grants are
read per request with no cache, since an unbounded one would defeat the
immediate-revocation promise; and Authentik roles have no broad day-one grants
yet, so /access/decision currently says no to everyone.

52 tests: 32 with no database over the rules, 20 through the routes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The attribute-level half of ADR5. Fields are published by allowlist, per
audience, at one chokepoint, because the Bureau's promises are field-shaped:
the owner's name and phone number sit on the same record as the water levels
the owner agreed to share.

core/field-allowlists.yml holds the allowlists, keyed by destination kind with
a per-slug override that replaces rather than extends. An audience with no
entry receives an empty record, not the whole one, so a column added next year
is invisible until someone lists it deliberately.

domain/field_projection.py holds the rules over plain dicts.
services/field_projection.py parses the configuration, validates it in full on
first read, and turns a model row into the record an audience receives. It is
called from services/visibility.py, below the routes: api/access.py never
projects anything itself, so a new route or output format cannot skip the rule
by forgetting to call it.

Validation is at load rather than at request time. An unknown field name, a
transform on a field nobody publishes, or an allowlist naming a never-public
field raises immediately, because the alternative is discovering a typo by
noticing data that should have been there -- or data that should not have been.

The never-public list wins over every allowlist and is applied twice, at load
and again at projection. It currently covers provenance columns, legacy AMPAPI
primary keys, and the free-text location and coordinate note columns, which
are where gate codes, lock combinations and candid landowner notes have
landed. Adding to that list is safe at any time; removing from it is a policy
decision with a named owner, and ADR5 records that nobody has been named yet.

Protection includes transformation, not only removal. `round` is the first
transform: the same well reaches a harvester at four decimal places and the
public web at two. Rounded rather than withheld, so protecting a landowner
does not mean dropping the well off the map.

/access/destination/{slug}/thing now returns the projected record and location
alongside the consented data types.

Not covered: the ogc_* views still select their own columns in SQL and gate on
release_status, so nothing on this path applies to them yet; only thing and
location are projectable entities; and field rules between internal roles --
contact information being AMP-only -- are not implemented.

Documented in docs/access-field-projection.md. 22 tests, most needing no
database.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

An empty grant table denies everyone, which is correct and useless:
/access/decision said no to the people who administer the system. This writes
down the access the Authentik roles already had, so nobody's access changes on
the day the visibility layer starts being consulted (ADR5, 5.2).

68 grants: seven roles x their capabilities x four data types, all globally
scoped. The mapping mirrors core/dependencies.py -- Viewer reads, Editor also
enters and corrects, Admin also administers, the AMP family the same, and
OGCInternal reads because the desktop-GIS mount has never written.

Lexicon* is not seeded: it gates vocabulary, not data. AMP.Staging is not
seeded because it gates a workbench that ships dark, and granting access to
something still being validated is the one outcome nobody intended.

The seeder will not resurrect a grant somebody revoked. Its skip check counts
revoked rows as already-seeded, because narrowing this baseline is the whole
point of writing it down, and a seeder that quietly undid a deliberate
revocation would be worse than no seeder. Every row it writes carries
granted_by = system:day-one-baseline and a reason naming the ADR, so a grant
that exists because of institutional history is distinguishable from one
somebody weighed. Each is audited as grant.created.

Exposed as `oco seed-access-grants`, which previews by default and needs
--apply to write. Grants are security state; creating them as a side effect of
a process start would be the kind of thing nobody remembers is happening. It
has not been run in any environment, so dev, staging and production still deny
everyone until somebody runs it there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Four rules on how to approach changes in this repo: state assumptions
before implementing, keep the solution minimal, keep diffs surgical, and
turn tasks into verifiable goals.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The projection chokepoint only covered payloads built by
services/visibility.py; the OGC views selected their own columns in SQL.
This closes that gap for all 27 public collections.

DescribedPostgreSQLProvider now looks its table up in the new ogc: block
of core/field-allowlists.yml and hands the result to pygeoapi as the
provider's `properties`, which is what _select_properties builds the
SELECT from. An unlisted column is never read out of Postgres, so it
cannot surface in a feature, in /schema, or in /queryables, and a filter
cannot probe for it. get_fields is narrowed to match. A collection with
no entry publishes nothing, and tests/test_ogc_projection.py fails on a
missing entry so it shows up in CI rather than in production. The
internal mount (ogc_internal_*) is not projected.

The lists were generated from what each view published on 2026-08-24
minus the never-public fields, so no consumer lost a field it was using.
Two leaks did close: eleven collections were publishing nma_pk_welldata
and ogc_temp_depth_measurements was publishing entered_by, a staff
member's name.

Also fixes PRINCIPAL_API_KEY, which said "api_key" where the lexicon
says "api key". The route validated against the constant, so every
API-key grant was rejected with a 422. A new test pins the domain
vocabularies to the lexicon enums so they cannot drift again.

Drops domain.access.published_thing_ids, which had no callers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Design-canvas artboards, deck sources and their generated PDFs. Working
material, not part of the API, and the PDFs are binary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

GET /access/grant required principal_id; there was no way to browse
every grant for an admin audit view. principal_id is now an optional
filter, alongside new capability/data_type/scope_type filters -- the
bare route lists everything.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

alembic/versions/79a3ab24627e_add_access_control_tables.py adds
permission_grant etc. but deliberately does not seed the
principal_type/capability/grant_scope_type/access_data_type lexicon
terms those columns FK to -- that's core/lexicon.json via
init_lexicon, kept out of the migration so a new capability is a data
change, not a migration.

entrypoint.sh only ran alembic upgrade head, so a fresh dev DB (e.g.
after dropping the postgres_data_dev volume) has the tables but no
terms, and any POST /access/grant 500s on a FK violation. Run
`oco initialize-lexicon` right after migrations; it's idempotent
(on_conflict_do_nothing), safe on every start. Dev-only --
staging/production deploy runs alembic directly and never calls this
script.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>